package bma.common.langutil.concurrent;

import java.util.concurrent.RejectedExecutionException;
import java.util.concurrent.TimeUnit;

public interface ScheduledExecutor {
	/**
	 * Creates and executes a one-shot action that becomes enabled after the
	 * given delay.
	 * 
	 * @param command
	 *            the task to execute
	 * @param delay
	 *            the time from now to delay execution
	 * @param unit
	 *            the time unit of the delay parameter
	 * @return boolean
	 * @throws RejectedExecutionException
	 *             if the task cannot be scheduled for execution
	 * @throws NullPointerException
	 *             if command is null
	 */
	public boolean schedule(Runnable command, long delay, TimeUnit unit);

	/**
	 * Creates and executes a periodic action that becomes enabled first after
	 * the given initial delay, and subsequently with the given period; that is
	 * executions will commence after <tt>initialDelay</tt> then
	 * <tt>initialDelay+period</tt>, then <tt>initialDelay + 2 * period</tt>,
	 * and so on. If any execution of the task encounters an exception,
	 * subsequent executions are suppressed. Otherwise, the task will only
	 * terminate via cancellation or termination of the executor. If any
	 * execution of this task takes longer than its period, then subsequent
	 * executions may start late, but will not concurrently execute.
	 * 
	 * @param command
	 *            the task to execute
	 * @param initialDelay
	 *            the time to delay first execution
	 * @param period
	 *            the period between successive executions
	 * @param unit
	 *            the time unit of the initialDelay and period parameters
	 * @return boolean
	 * @throws RejectedExecutionException
	 *             if the task cannot be scheduled for execution
	 * @throws NullPointerException
	 *             if command is null
	 * @throws IllegalArgumentException
	 *             if period less than or equal to zero
	 */
	public boolean scheduleAtFixedRate(Runnable command, long initialDelay,
			long period, TimeUnit unit);

	/**
	 * Creates and executes a periodic action that becomes enabled first after
	 * the given initial delay, and subsequently with the given delay between
	 * the termination of one execution and the commencement of the next. If any
	 * execution of the task encounters an exception, subsequent executions are
	 * suppressed. Otherwise, the task will only terminate via cancellation or
	 * termination of the executor.
	 * 
	 * @param command
	 *            the task to execute
	 * @param initialDelay
	 *            the time to delay first execution
	 * @param delay
	 *            the delay between the termination of one execution and the
	 *            commencement of the next
	 * @param unit
	 *            the time unit of the initialDelay and delay parameters
	 * @return boolean
	 * @throws RejectedExecutionException
	 *             if the task cannot be scheduled for execution
	 * @throws NullPointerException
	 *             if command is null
	 * @throws IllegalArgumentException
	 *             if delay less than or equal to zero
	 */
	public boolean scheduleWithFixedDelay(Runnable command, long initialDelay,
			long delay, TimeUnit unit);
}
